fix(plugin-auth): let ImportProtocolLike type the admin import protocol's three members - #17489

Fixes #17422

Clause-②: no

_(declaration line written by the domain:services review seat, not by the implementer. Check Changeset went RED on head fb659886 for the ABSENCE of this line, not for a wrong one: with no declaration and no needs:contract-review carrier, the gate resolves not-measured-material — a moved package graded patch is exactly what a yes would have refused. Declaring no resolves it as not-declared. Measured on THIS diff, ⛔ not predicted from the dispatch — the dispatch predicted no on the reasoning that deleting a parameter annotation only narrows, and that reasoning did NOT cover the new refusal this diff adds, so both limbs were re-measured:

• limb A (accept set): unchanged. A findData call arriving without query was already rejected — by an incidental TypeError on a property read of undefined. It is now rejected by a named throw. Nothing is newly accepted and nothing is newly refused; the same call fails, legibly. ⛔ Not a widening.
• limb B (public surface): unchanged. 0 added lines containing export in packages/** outside tests, against a control of 23 added source lines. The 1 added code: entry is INVALID_REQUEST, which is already registered in packages/spec/src/api/error-code-ledger.zod.ts — and @objectstack/plugin-auth is already listed as an owner of it (:550, inside the owner block opening at :536), so check:error-code-provenance needs neither a new owner-key row nor a PROVENANCE_WAIVERS entry. ⛔ No packages/spec edit is owed, and none is made.

⇒ no + a patch changeset is the correct and consistent pair here. ⛔ Do not delete this line; the gate reads the body, so removing it re-reds the PR.)_

What this closes

packages/plugins/plugin-auth/src/admin-import-users.ts is the only hand-written in-repo implementor of the runner's ImportProtocolLike, and it annotated all three required members args: any. An explicit parameter annotation wins over the contextual type, so the contract #16952 declared held every implementor except the one with the demonstrated history — the file whose frozen $filter read once degraded the import's duplicate probe into match-everything and updated the wrong users.

Three annotations removed, all members of the const protocol: ImportProtocolLike = { literal (positions re-derived by text, not from the card's line numbers):

The three OPTIONAL members of the interface — createManyData, insertManyData, validateData — are not implemented by this literal (grep -c for each: 0 implementations; createManyData's absence is deliberate and commented in place). So the class the card names is exactly three here, not "three plus".

Repo-wide sweep for other implementors: every other ImportProtocolLike literal is in packages/rest's own test doubles, and #16952 already annotated those FROM the exported declaration (Parameters[ImportProtocolLike['findData']] and siblings). The two production runImport call sites in rest-server.ts hand it the real DataProtocol service, not a hand-written literal.

Triage's fork, answered: MERELY UNTYPED — not a dialect divergence

Triage asked to stop and report if the errors revealed a genuinely different dialect. They do not. Every key this file reads is one the protocol declares:

• findData reads args.object, args.query.where, args.query.limit — FindDataRequest declares object and query; QuerySchema declares where and limit.
• createData reads args.data — declared, required.
• updateData reads args.data and args.id — both declared, both required.

The compiler reported two errors and both are about optionality, not about an undeclared key:

src/admin-import-users.ts(367,21): error TS18048: 'args.query' is possibly 'undefined'.
src/admin-import-users.ts(368,21): error TS18048: 'args.query' is possibly 'undefined'.

FindDataRequestSchema declares query optional (packages/spec/src/api/protocol.zod.ts:1865), while all three of the runner's findData dispatch sites always supply it (import-runner.ts:446, :489, :612, all through findArgsBase). So the file was reading the right key untypedly, and the contract's only complaint is that the file never wrote down what it does when the caller omits query.

Resolution — one change, no cast. findData now states the refusal instead of leaning on an incidental TypeError from a property read on undefined:

const query = args.query;
if (!query) {
  throw Object.assign(
    new Error('import-users: findData was called without a query — refusing to match every user'),
    { code: 'INVALID_REQUEST' },
  );
}
const where = query.where;
const limit = query.limit;

No as any, no @ts-expect-error, no !, no widened local alias, and deliberately no args.query ?? {} and no args.query?.where — both of those spell match-everything, which is the exact regression the file's own comment block is about. INVALID_REQUEST is already registered for @objectstack/plugin-auth in packages/spec/src/api/error-code-ledger.zod.ts:550, so no spec file is touched by this PR (⛔ packages/spec was the lane's red line) and pnpm check:error-code-casing stays green.

packages/rest/src/import-runner.ts was read only. Nothing in it needed to move.

Reverse verification — the green is a reading, not a dead check

Two legs plus a control, then restored by state.

Leg 2 is the point: the probe does not decide the colour — the annotation does. (The card cited TS2353; that came from an object-literal probe. This probe is a property READ, so the same live type answers TS2339. Direction as predicted; the code differs because the probe shape differs.)

Does a regression test for the $filter to match-everything history exist?

Behaviourally, yes — and it discriminates. Ablated findData back to the pre-#16950 read ((args.query as any)?.$filter ?? {}) and ran the sibling suite: 2 of 26 failed —

• upsert > matches by email … — AssertionError: expected 2 to be 1 (with where empty the second row matches the existing user instead of creating one: the wrong-user update, reproduced)
• upsert > matches by phone_number when enabled — the expect(find).toHaveBeenCalledWith(…, objectContaining({ where: … })) pin fails.

Restored by state (blob hash equal to HEAD, git diff HEAD empty).

For the opt-out itself, no — nothing could see it. Re-annotating all three members any and re-running: tsc --noEmit exit 0 and all 26 behavioural tests green. That is precisely how this hole stayed open under a green #16952. So this PR adds the missing guard as a source pin in the package's own test sibling (the same technique rest-server-canonical-query-ast.test.ts §1b uses for the declaration half). Ablated: with the three annotations restored, 3 of 30 fail — exactly the three new pins — and the other 27 stay green.

Verification

Working tree clean at fb6598867; every exit code captured before any pipe.

• pnpm --filter @objectstack/plugin-auth build — exit 0, check-dts-emitted: 2/2 declared declaration file(s) present.
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0 (tsc --noEmit + tsconfig.examples.json + check:test-typecheck; the test layer compiles under tsconfig.test.json with its shrink-only debt ledger unmoved: 10 files / 94 errors / 23 pinned signatures).
• pnpm --filter @objectstack/plugin-auth test — exit 0, 106 files / 2260 tests passed.
• pnpm lint (eslint . --no-inline-config, the whole repo, not a narrowed set) — exit 0 in 1m53s at this same head.
• Dependency closure built first: pnpm --filter '@objectstack/plugin-auth^...' build — exit 0, so tsc read a freshly built packages/rest/dist/index.d.ts carrying the narrowed interface (verified by grepping the three member signatures out of the emitted .d.ts), not a stale one.
• scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 61 families; all 61 run, 59 exit 0, 2 exit 3 = PREREQUISITE NOT MET = NOT MEASURED (check:dual-build-cjs-loads, check:type-check-debt — both refuse without a whole-workspace build, which is CI's Build Core / TypeScript Type Check, not a package-scoped local tier). --ran reconciliation with exit codes recorded: 61 derived, 59 run, 2 NOT-MEASURED, 0 UNRUN.
• The five artifact-roster gates whose roster sits under a path in this diff were run rather than read as silent: check-changeset-fixed, check:auth-mount-ledger, check:authz-resolver, check:error-code-casing, check:filter-alias-parity — all exit 0.
• Heavy runs went through scripts/pm/os-verify-lock.sh; every verdict read from its VERDICT command-exit line.

Acceptance notes

Observations from this file, deliberately not changed here and not filed (none meets the file-an-issue bar — no repro, no violated declared contract, no metadata-authoring trap):

• IdentityImportEngine at src/admin-import-users.ts:89–:91 (find(objectName: string, query?: any), update(…, data: any, options?: any), insert(…)) is a different, local, engine-shaped interface and not part of ImportProtocolLike. Left exactly as found, per the dispatch. Typing it against ObjectQL's real engine surface would be its own card; no PR or seat is in flight over it today.
• createData / updateData still spell args?.data ?? {}. Both request types declare data required, so the fallback is now provably unreachable rather than merely unused — belt-and-braces of the family Prime Directive Add comprehensive test suite for Zod schema validation #12 names, but not a defect and not compiler-forced. The next PR touching this literal is the natural carrier.
• engine.find(args.object, { where, limit, context: SYSTEM_CTX } as any) keeps its pre-existing as any on the OPTIONS bag (a consequence of the local interface above, not of the protocol). pnpm check:query-options-erasure is green over it.
• The runner's docblock instruction ("Leave the parameter unannotated and let this declaration type it") is now enforced for this implementor only, by the pin added here. A future implementor in another package gets no such guard; a repo-wide check would be a separate piece of work, and nothing violates the contract today.

Generated by Claude Code